Gitit User’s Guide.page (22282B)
1 --- 2 format: Markdown 3 ... 4 5 Gitit 6 ===== 7 8 Gitit is a wiki program written in Haskell. It uses [Happstack] for 9 the web server and [pandoc] for markup processing. Pages and uploaded 10 files are stored in a [git], [darcs], or [mercurial] repository 11 and may be modified either by using the VCS's command-line tools or 12 through the wiki's web interface. By default, pandoc's extended version 13 of markdown is used as a markup language, but reStructuredText, LaTeX, HTML, 14 DocBook, or Emacs Org-mode markup can also be used. Pages can be exported in a 15 number of different formats, including LaTeX, RTF, OpenOffice ODT, and 16 MediaWiki markup. Gitit can be configured to display TeX math (using 17 [texmath]) and highlighted source code (using [highlighting-kate]). 18 19 Other features include 20 21 * plugins: dynamically loaded page transformations written in Haskell 22 (see "Network.Gitit.Interface") 23 24 * categories 25 26 * TeX math 27 28 * syntax highlighting of source code files and code snippets (using 29 highlighting-kate) 30 31 * caching 32 33 * Atom feeds (site-wide and per-page) 34 35 * a library, "Network.Gitit", that makes it simple to include a gitit 36 wiki in any happstack application 37 38 [git]: http://git.or.cz 39 [darcs]: http://darcs.net 40 [mercurial]: http://mercurial.selenic.com/ 41 [pandoc]: http://pandoc.org 42 [Happstack]: http://happstack.com 43 [highlighting-kate]: http://johnmacfarlane.net/highlighting-kate/ 44 [texmath]: http://github.com/jgm/texmath/tree/master 45 46 Getting started 47 =============== 48 49 Compiling and installing gitit 50 ------------------------------ 51 52 The most reliable way to install gitit from source is to get the 53 [stack] tool. Then clone the gitit repository and use stack 54 to install: 55 56 git clone https://github.com/jgm/gitit 57 cd gitit 58 stack install 59 60 Alternatively, instead of using [stack], you can get the 61 [Haskell Platform] and do the following: 62 63 cabal update 64 cabal install gitit 65 66 This will install the latest released version of gitit. 67 To install a version of gitit checked out from the repository, 68 change to the gitit directory and type: 69 70 cabal install 71 72 The `cabal` tool will automatically install all of the required haskell 73 libraries. If all goes well, by the end of this process, the latest 74 release of gitit will be installed in your local `.cabal` directory. You 75 can check this by trying: 76 77 gitit --version 78 79 If that doesn't work, check to see that `gitit` is in your local 80 cabal-install executable directory (usually `~/.cabal/bin`). And make 81 sure `~/.cabal/bin` is in your system path. 82 83 [stack]: https://github.com/commercialhaskell/stack 84 [Haskell Platform]: https://www.haskell.org/platform/ 85 86 Running gitit 87 ------------- 88 89 To run gitit, you'll need `git` in your system path. (Or `darcs` or 90 `hg`, if you're using darcs or mercurial to store the wiki data.) 91 92 Gitit assumes that the page files (stored in the git repository) are 93 encoded as UTF-8. Even page names may be UTF-8 if the file system 94 supports this. So you should make sure that you are using a UTF-8 locale 95 when running gitit. (To check this, type `locale`.) 96 97 Switch to the directory where you want to run gitit. This should be a 98 directory where you have write access, since three directories, `static`, 99 `templates`, and `wikidata`, and two files, `gitit-users` and `gitit.log`, 100 will be created here. To start gitit, just type: 101 102 gitit 103 104 If all goes well, gitit will do the following: 105 106 1. Create a git repository, `wikidata`, and add a default front page. 107 2. Create a `static` directory containing files to be treated as 108 static files by gitit. 109 3. Create a `templates` directory containing HStringTemplate templates 110 for wiki pages. 111 4. Start a web server on port 5001. 112 113 Check that it worked: open a web browser and go to 114 <http://localhost:5001>. 115 116 You can control the port that gitit runs on using the `-p` option: 117 `gitit -p 4000` will start gitit on port 4000. Additional runtime 118 options are described by `gitit -h`. 119 120 Using gitit 121 =========== 122 123 Wiki links and formatting 124 ------------------------- 125 126 For instructions on editing pages and creating links, see the "Help" page. 127 128 Gitit interprets links with empty URLs as wikilinks. Thus, in markdown 129 pages, `[Front Page]()` creates an internal wikilink to the page `Front 130 Page`. In reStructuredText pages, `` `Front Page <>`_ `` has the same 131 effect. 132 133 If you want to link to a directory listing for a subdirectory, use a 134 trailing slash: `[foo/bar/]()` creates a link to the directory for 135 `foo/bar`. 136 137 Page metadata 138 ------------- 139 140 Pages may optionally begin with a metadata block. Here is an example: 141 142 --- 143 format: latex+lhs 144 categories: haskell math 145 toc: no 146 title: Haskell and 147 Category Theory 148 ... 149 150 \section{Why Category Theory?} 151 152 The metadata block consists of a list of key-value pairs, each on a 153 separate line. If needed, the value can be continued on one or more 154 additional line, which must begin with a space. (This is illustrated by 155 the "title" example above.) The metadata block must begin with a line 156 `---` and end with a line `...` optionally followed by one or more blank 157 lines. (The metadata block is a valid YAML document, though not all YAML 158 documents will be valid metadata blocks.) 159 160 Currently the following keys are supported: 161 162 format 163 : Overrides the default page type as specified in the configuration file. 164 Possible values are `markdown`, `rst`, `latex`, `html`, `markdown+lhs`, 165 `rst+lhs`, `latex+lhs`. (Capitalization is ignored, so you can also 166 use `LaTeX`, `HTML`, etc.) The `+lhs` variants indicate that the page 167 is to be interpreted as literate Haskell. If this field is missing, 168 the default page type will be used. 169 170 categories 171 : A space or comma separated list of categories to which the page belongs. 172 173 toc 174 : Overrides default setting for table-of-contents in the configuration file. 175 Values can be `yes`, `no`, `true`, or `false` (capitalization is ignored). 176 177 title 178 : By default the displayed page title is the page name. This metadata element 179 overrides that default. 180 181 Highlighted source code 182 ----------------------- 183 184 If gitit was compiled against a version of pandoc that has highlighting 185 support (see above), you can get highlighted source code by using 186 [delimited code blocks]: 187 188 ~~~ {.haskell .numberLines} 189 qsort [] = [] 190 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++ 191 qsort (filter (>= x) xs) 192 ~~~ 193 194 To see what languages your pandoc was compiled to highlight: 195 196 pandoc -v 197 198 [delimited code blocks]: http://pandoc.org/README.html#delimited-code-blocks 199 200 Configuring and customizing gitit 201 ================================= 202 203 Configuration options 204 --------------------- 205 206 Use the option `-f [filename]` to specify a configuration file: 207 208 gitit -f my.conf 209 210 The configuration can be split between several files: 211 212 gitit -f my.conf -f additional.conf 213 214 One use case is to keep sensible part of the configuration outside of a SCM 215 (oauth client secret for example). 216 217 If this option is not used, gitit will use a default configuration. 218 To get a copy of the default configuration file, which you 219 can customize, just type: 220 221 gitit --print-default-config > my.conf 222 223 The default configuration file is documented with comments throughout. 224 225 The `static` directory 226 ---------------------- 227 228 On receiving a request, gitit always looks first in the `static` 229 directory (or in whatever directory is specified for `static-dir` in 230 the configuration file). If a file corresponding to the request is 231 found there, it is served immediately. If the file is not found in 232 `static`, gitit next looks in the `static` subdirectory of gitit's data 233 file (`$CABALDIR/share/gitit-x.y.z/data`). This is where default css, 234 images, and javascripts are stored. If the file is not found there 235 either, gitit treats the request as a request for a wiki page or wiki 236 command. 237 238 So, you can throw anything you want to be served statically (for 239 example, a `robots.txt` file or `favicon.ico`) in the `static` 240 directory. You can override any of gitit's default css, javascript, or 241 image files by putting a file with the same relative path in `static`. 242 Note that gitit has a default `robots.txt` file that excludes all 243 URLs beginning with `/_`. 244 245 Note: if you set `static-dir` to be a subdirectory of `repository-path`, 246 and then add the files in the static directory to your repository, you 247 can ensure that others who clone your wiki repository get these files 248 as well. It will not be possible to modify these files using the web 249 interface, but they will be modifiable via git. 250 251 Using a VCS other than git 252 -------------------------- 253 254 By default, gitit will store wiki pages in a git repository in the 255 `wikidata` directory. If you'd prefer to use darcs instead of git, 256 you need to add the following field to the configuration file: 257 258 repository-type: Darcs 259 260 If you'd prefer to use mercurial, add: 261 262 repository-type: Mercurial 263 264 This program may be called "darcsit" instead of "gitit" when a darcs 265 backend is used. 266 267 Note: we recommend that you use gitit/darcsit with darcs version 268 2.3.0 or greater. If you must use an older version of darcs, then 269 you need to compile the filestore library without the (default) 270 maxcount flag, before (re)installing gitit: 271 272 cabal install --reinstall filestore -f-maxcount 273 cabal install --reinstall gitit 274 275 Otherwise you will get an error when you attempt to access your 276 repository. 277 278 Changing the theme 279 ------------------ 280 281 To change the look of the wiki, you can modify `custom.css` in 282 `static/css`. 283 284 To change the look of printed pages, copy gitit's default `print.css` 285 to `static/css` and modify it. 286 287 The logo picture can be changed by copying a new PNG file to 288 `static/img/logo.png`. The default logo is 138x155 pixels. 289 290 To change the footer, modify `templates/footer.st`. 291 292 For more radical changes, you can override any of the default 293 templates in `$CABALDIR/share/gitit-x.y.z/data/templates` by copying 294 the file into `templates`, modifying it, and restarting gitit. The 295 `page.st` template is the master template; it includes the others. 296 Interpolated variables are surrounded by `$`s, so `literal $` must 297 be backslash-escaped. 298 299 Adding support for math 300 ----------------------- 301 302 To write math on a markdown-formatted wiki page, just enclose it 303 in dollar signs, as in LaTeX: 304 305 Here is a formula: $\frac{1}{\sqrt{c^2}}$ 306 307 You can write display math by enclosing it in double dollar signs: 308 309 $$\frac{1}{\sqrt{c^2}}$$ 310 311 Gitit can display TeX math in three different ways, depending on the 312 setting of `math` in the configuration file: 313 314 1. `mathml` (default): Math will be converted to MathML using 315 [texmath]. This method works with IE+mathplayer, Firefox, and 316 Opera, but not Safari. 317 318 2. `jsMath`: Math will be rendered using the [jsMath] javascript. 319 If you want to use this method, download `jsMath` and `jsMath 320 Image Fonts` from the [jsMath download page]. You'll have two 321 `.zip` archives. Unzip them both in the `static/js` directory (a new 322 subdirectory, `jsMath`, will be created). This works with all 323 browsers, but is slower and not as nice looking as MathML. 324 325 3. `raw`: Math will be rendered as raw LaTeX codes. 326 327 [jsMath]: http://www.math.union.edu/~dpvc/jsmath/ 328 [jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663 329 330 Restricting access 331 ------------------ 332 333 If you want to limit account creation on your wiki, the easiest way to do this 334 is to provide an `access-question` in your configuration file. (See the commented 335 default configuration file.) Nobody will be able to create an account without 336 knowing the answer to the access question. 337 338 Another approach is to use HTTP authentication. (See the config file comments on 339 `authentication-method`.) 340 341 Authentication through github 342 ----------------------------- 343 344 If you want to authenticate the user from github through oauth2, you need to 345 register your app with github to obtain a OAuth client secret and add the 346 following section to your configuration file: 347 348 ``` 349 [Github] 350 oauthclientid: 01239456789abcdef012 351 oauthclientsecret: 01239456789abcdef01239456789abcdef012394 352 oauthcallback: http://mysite/_githubCallback 353 oauthoauthorizeendpoint: https://github.com/login/oauth/authorize 354 oauthaccesstokenendpoint: https://github.com/login/oauth/access_token 355 ## Uncomment if you are checking membership against an organization and change 356 ## gitit-testorg to this organization: 357 # github-org: gitit-testorg 358 ``` 359 360 The github authentication uses the scope `user:email`. This way, gitit gets the 361 email of the user, and the commit can be assigned to the right author if the 362 wikidata repository is pushed to github. Additionally, it uses `read:org` if you 363 uses the option `github-org` to check membership against an organization. 364 365 To push your repository to gitub after each commit, you can add the file 366 `post-commit` with the content below in the .git/hooks directory of your 367 wikidata repository. 368 369 ``` 370 #!/bin/sh 371 git push origin master 2>> logit 372 ``` 373 374 Plugins 375 ======= 376 377 Plugins are small Haskell programs that transform a wiki page after it 378 has been converted from Markdown or another source format. See the example 379 plugins in the `plugins` directory. To enable a plugin, include the path to the 380 plugin (or its module name) in the `plugins` field of the configuration file. 381 (If the plugin name starts with `Network.Gitit.Plugin.`, gitit will assume that 382 the plugin is an installed module and will not look for a source file.) 383 384 Plugin support is enabled by default. However, plugin support makes 385 the gitit executable considerably larger and more memory-hungry. 386 If you don't need plugins, you may want to compile gitit without plugin 387 support. To do this, unset the `plugins` Cabal flag: 388 389 cabal install --reinstall gitit -f-plugins 390 391 Note also that if you compile gitit for executable profiling, attempts 392 to load plugins will result in "internal error: PAP object entered!" 393 394 Accessing the wiki through git 395 ============================== 396 397 All the pages and uploaded files are stored in a git repository. By 398 default, this lives in the `wikidata` directory (though this can be 399 changed through configuration options). So you can interact with the 400 wiki using git command line tools: 401 402 git clone ssh://my.server.edu/path/of/wiki/wikidata 403 cd wikidata 404 vim Front\ Page.page # edit the page 405 git commit -m "Added message about wiki etiquette" Front\ Page.page 406 git push 407 408 If you now look at the Front Page on the wiki, you should see your changes 409 reflected there. Note that the pages all have the extension `.page`. 410 411 If you are using the darcs or mercurial backend, the commands will 412 be slightly different. See the documentation for your VCS for 413 details. 414 415 Performance 416 =========== 417 418 Caching 419 ------- 420 421 By default, gitit does not cache content. If your wiki receives a lot of 422 traffic or contains pages that are slow to render, you may want to activate 423 caching. To do this, set the configuration option `use-cache` to `yes`. 424 By default, rendered pages, highlighted source files, and exported PDFs 425 will be cached in the `cache` directory. (Another directory can be 426 specified by setting the `cache-dir` configuration option.) 427 428 Cached pages are updated when pages are modified using the web 429 interface. They are not updated when pages are modified directly through 430 git or darcs. However, the cache can be refreshed manually by pressing 431 Ctrl-R when viewing a page, or by sending an HTTP GET or POST request to 432 `/_expire/path/to/page`, where `path/to/page` is the name of the page to 433 be expired. 434 435 Users who frequently update pages using git or darcs may wish to add a 436 hook to the repository that makes the appropriate HTTP request to expire 437 pages when they are updated. To facilitate such hooks, the gitit cabal 438 package includes an executable `expireGititCache`. Assuming you are 439 running gitit at port 5001 on localhost, and the environment variable 440 `CHANGED_FILES` contains a list of the files that have changed, you can 441 expire their cached versions using 442 443 expireGititCache http://localhost:5001 $CHANGED_FILES 444 445 Or you can specify the files directly: 446 447 expireGititCache http://localhost:5001 "Front Page.page" foo/bar/baz.c 448 449 This program will return a success status (0) if the page has been 450 successfully expired (or if it was never cached in the first place), 451 and a failure status (> 0) otherwise. 452 453 The cache is persistent through restarts of gitit. To expire all cached 454 pages, simply remove the `cache` directory. 455 456 Idle 457 ---- 458 459 By default, GHC's runtime will repeatedly attempt to collect garbage 460 when an executable like Gitit is idle. This means that gitit will, after 461 the first page request, never use 0% CPU time and sleep, but will use 462 ~1%. This can be bad for battery life, among other things. 463 464 To fix this, one can disable the idle-time GC with the runtime flag 465 `-I0`: 466 467 gitit -f my.conf +RTS -I0 -RTS 468 469 470 Note: 471 472 To enable RTS, cabal needs to pass the compile flag `-rtsopts` to GHC while installing. 473 474 cabal install --reinstall gitit --ghc-options="-rtsopts" 475 476 Using gitit with apache 477 ======================= 478 479 Most users who run a public-facing gitit will want gitit to appear 480 at a nice URL like `http://wiki.mysite.com` or 481 `http://mysite.com/wiki` rather than `http://mysite.com:5001`. 482 This can be achieved using apache's `mod_proxy`. 483 484 Proxying to `http://wiki.mysite.com` 485 ------------------------------------ 486 487 Set up your DNS so that `http://wiki.mysite.com` maps to 488 your server's IP address. Make sure that the `mod_proxy`, `mod_proxy_http` and `mod_rewrite` modules are 489 loaded, and set up a virtual host with the following configuration: 490 491 <VirtualHost *> 492 ServerName wiki.mysite.com 493 DocumentRoot /var/www/ 494 RewriteEngine On 495 ProxyPreserveHost On 496 ProxyRequests Off 497 498 <Proxy *> 499 Order deny,allow 500 Allow from all 501 </Proxy> 502 503 ProxyPassReverse / http://127.0.0.1:5001 504 RewriteRule ^(.*) http://127.0.0.1:5001$1 [P] 505 506 ErrorLog /var/log/apache2/error.log 507 LogLevel warn 508 509 CustomLog /var/log/apache2/access.log combined 510 ServerSignature On 511 512 </VirtualHost> 513 514 Reload your apache configuration and you should be all set. 515 516 Using nginx to achieve the same 517 ------------------------------- 518 519 Drop a file called `wiki.example.com.conf` into `/etc/nginx/conf.d` 520 (or where ever your distribution puts it). 521 522 server { 523 listen 80; 524 server_name wiki.example.com 525 location / { 526 proxy_pass http://127.0.0.1:5001/; 527 proxy_set_header X-Real-IP $remote_addr; 528 proxy_redirect off; 529 } 530 access_log /var/log/nginx/wiki.example.com.log main; 531 } 532 533 Reload your nginx config and you should be all set. 534 535 536 Proxying to `http://mysite.com/wiki` 537 ------------------------------------ 538 539 Make sure the `mod_proxy`, `mod_headers`, `mod_proxy_http`, 540 and `mod_proxy_html` modules are loaded. `mod_proxy_html` 541 is an external module, which can be obtained [here] 542 (http://apache.webthing.com/mod_proxy_html/). It rewrites URLs that 543 occur in web pages. Here we will use it to rewrite gitit's links so that 544 they all begin with `/wiki/`. 545 546 First, tell gitit not to compress pages, since `mod_proxy_html` needs 547 uncompressed pages to parse. You can do this by setting the gitit 548 configuration option 549 550 compress-responses: no 551 552 Second, modify the link in the `reset-password-message` in the 553 configuration file: instead of 554 555 http://$hostname$:$port$$resetlink$ 556 557 set it to 558 559 http://$hostname$/wiki$resetlink$ 560 561 Restart gitit. 562 563 Now add the following lines to the apache configuration file for the 564 `mysite.com` server: 565 566 # These commands will proxy /wiki/ to port 5001 567 568 ProxyRequests Off 569 570 <Proxy *> 571 Order deny,allow 572 Allow from all 573 </Proxy> 574 575 ProxyPass /wiki/ http://127.0.0.1:5001/ 576 577 <Location /wiki/> 578 SetOutputFilter proxy-html 579 ProxyPassReverse / 580 ProxyHTMLURLMap / /wiki/ 581 ProxyHTMLDocType "<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>" XHTML 582 RequestHeader unset Accept-Encoding 583 </Location> 584 585 Reload your apache configuration and you should be set. 586 587 For further information on the use of `mod_proxy_http` to rewrite URLs, 588 see the [`mod_proxy_html` guide]. 589 590 [`mod_proxy_html` guide]: http://apache.webthing.com/mod_proxy_html/guide.html 591 592 Using gitit as a library 593 ======================== 594 595 By importing the module `Network.Gitit`, you can include a gitit wiki 596 (or several of them) in another happstack application. There are some 597 simple examples in the haddock documentation for `Network.Gitit`. 598 599 Reporting bugs 600 ============== 601 602 Bugs may be reported (and feature requests filed) at 603 <https://github.com/jgm/gitit/issues>. 604 605 There is a mailing list for users and developers at 606 <http://groups.google.com/group/gitit-discuss>. 607 608 Acknowledgements 609 ================ 610 611 A number of people have contributed patches: 612 613 - Gwern Branwen helped to optimize gitit and wrote the 614 InterwikiPlugin. He also helped with the Feed module. 615 - Simon Michael contributed the patch adding RST support. 616 - Henry Laxen added support for password resets and helped with 617 the apache proxy instructions. 618 - Anton van Straaten made the process of page generation 619 more modular by adding Gitit.ContentTransformer. 620 - Robin Green helped improve the plugin API and interface, and 621 fixed a security problem with the reset password code. 622 - Thomas Hartman helped improve the index page, making directory 623 browsing persistent, and fixed a bug in template recompilation. 624 - Justin Bogner improved the appearance of the preview button. 625 - Kohei Ozaki contributed the ImgTexPlugin. 626 - Michael Terepeta improved validation of change descriptions. 627 - mightybyte suggested making gitit available as a library, 628 and contributed a patch to ifLoggedIn that was needed to 629 make gitit usable with a custom authentication scheme. 630 631 I am especially grateful to the darcs team for using darcsit for 632 their public-facing wiki. This has helped immensely in identifying 633 issues and improving performance. 634 635 Gitit's default visual layout is shamelessly borrowed from Wikipedia. 636 The stylesheets are influenced by Wikipedia's stylesheets and by the 637 bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in 638 `img/icons` come from bluetrip as well. 639